---
title: DBConnectionAPI overview
summary: Purpose, business context, and capability summary for the DBConnectionAPI REST API.
status: draft
owner: Architecture
last_reviewed: 2026-10-09
---

# DBConnectionAPI overview

DBConnectionAPI hands authorized callers a ready-to-use database connection string for a named Oracle, SQL Server or PostgreSQL target. It builds the string from a per-database-type template and a per-user secure credential, both held in the SAIF Environment API, so that templates and credentials are sourced centrally rather than held by each caller. The responses themselves carry credential material, so callers must protect them accordingly. It also offers an administrative inspection surface that returns the individual credential parts.

## Purpose
- Compose connection strings for Oracle, SQL Server and PostgreSQL from Environment API templates and secure credentials.
- Validate Oracle and SQL Server strings with a connectivity probe (retry on transient failure) and cache the validated result in process memory.
- Expose an administrative surface that returns raw credential parts for troubleshooting.

## Business context

The service acts on behalf of callers that need to reach a database: it resolves the caller-named server, instance and user into a connection string and confirms that Oracle and SQL Server strings work before returning them. It reads and writes no business data in any table. It owns an in-memory cache of composed strings and nothing else. The effect of its unavailability on callers is not determined from source**.

| Attribute | Value |
| --- | --- |
| Business domain | Database connection provisioning |
| Owning team | `Architecture` (OpenTelemetry `Owner` value on the host builder in `Program.cs`) |
| Data ownership | None — in-memory connection cache only; credentials and templates are owned by the SAIF Environment API |
| Criticality | Not determined from source |

## Capability summary

| Capability | Owning component | Endpoints | Description |
| --- | --- | --- | --- |
| Retrieve a SQL Server connection string | `ConnectionsController` | [GET /v1/Connections/SQL/{server}/{instance}/{username}](endpoints/connections.md#get-v1-connections-sql-server-instance-username) | Returns a validated, cached SQL Server connection string |
| Retrieve a PostgreSQL connection string | `ConnectionsController` | [GET /v1/Connections/PostgreSQL/{instance}/{username}](endpoints/connections.md#get-v1-connections-postgresql-instance-username) | Returns a composed PostgreSQL connection string; it is not probed |
| Retrieve an Oracle connection string | `ConnectionsController` | [GET /v1/Connections/ORA/{instance}/{username}](endpoints/connections.md#get-v1-connections-ora-instance-username) | Returns a validated, cached Oracle connection string |
| Inspect Oracle credential parts | `AdminController` | [POST /v1/Admin/GetOracleConnectionInfo](endpoints/admin.md#post-v1-admin-getoracleconnectioninfo) | Returns raw credential parts and the composed string, without probe or cache |
| Inspect PostgreSQL credential parts | `AdminController` | [POST /v1/Admin/GetPostgresConnectionInfo](endpoints/admin.md#post-v1-admin-getpostgresconnectioninfo) | Same, for PostgreSQL |
| Inspect SQL Server credential parts | `AdminController` | [POST /v1/Admin/GetSqlConnectionInfo](endpoints/admin.md#post-v1-admin-getsqlconnectioninfo) | Same, for SQL Server |

The full catalog is on [Endpoints](endpoints.md). The rules behind these capabilities are on [Business rules](business-rules.md), for example the caching rule [BR-DBC-001](business-rules.md#br-dbc-001-serve-from-the-cache-when-the-key-is-present) and the credential-disclosure rule [BR-DBC-023](business-rules.md#br-dbc-023-admin-inspection-discloses-raw-credentials).

## Request and response format

| Aspect | Finding |
| --- | --- |
| Media types | Not declared (`[Produces]` and `[Consumes]` absent). Connections actions return a `string` that the framework normally writes as `text/plain`*; Admin actions return a JSON object |
| Serializer | Not configured in source; decided inside the opaque `CoreAPIStartup` base** (System.Text.Json by framework default*) |
| Serializer settings | Framework defaults; no converters, naming policy or null handling in source |
| Response envelope | No envelope. Connections return a bare string; Admin returns `Dictionary<string,string>` as a JSON object; errors are written by opaque package middleware† whose exact body is not visible in source** |

## Non-documented artifacts

- None found: the project has no Razor views, Razor Pages, `wwwroot` or view registrations, so nothing was excluded from this document set.

## Related documentation
- [API index](index.md)
- [Architecture](architecture.md)
- [Hosting pipeline](hosting-pipeline.md)
- [Endpoints](endpoints.md)
- [Authentication and authorization](authentication-authorization.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Data model](data-model.md)
- [Operational runbook](operational-runbook.md)
- [Tech debt](tech-debt.md)

> **Note:** Statements marked with `†` are derived from dependency library
> documentation via the Legends CLI. Statements marked with `*` were inferred
> from code structure or contextual evidence. Statements marked with `**` could
> not be confirmed; treat as unknown until verified.

## Sources
- DBConnectionAPI/DBConnectionAPI/Program.cs
- DBConnectionAPI/DBConnectionAPI/Startup.cs
- DBConnectionAPI/DBConnectionAPI/Controllers/ConnectionsController.cs
- DBConnectionAPI/DBConnectionAPI/Controllers/AdminController.cs
- DBConnectionAPI/DBConnectionAPI/Services/ConnectionManager.cs